…stem (#270903)

# Summary
This PR is extracted from
[#270286](#270286) as the first of
two stacked PRs. This first PR contains the needed changes in Agent
Builder to support adding several attachments as a single batch to the
chat. This followup [PR](#270904)
adds the possibility bulk add Alerts to the chat.

## What

This PR introduces `AttachmentGroup` as a client-side grouping primitive
and `group_id` as a first-class optional field on `Attachment`,
`VersionedAttachment`, and `AttachmentInput`. The group concept is
dissolved at the `flattenAttachments` serialization boundary —
individual items are stamped with `group_id` — and the full pipeline
(server routes, state manager, agent execution) threads the field
through to persistence and presentation.

## Why

Enables consumers (e.g. the Security Solution bulk-alerts feature) to
attach a batch of items as a single logical group, have them
deduplicated to one chip in chat history, and removed atomically. The
[follow-up PR](#270904) shows the
first concrete use: bulk-adding alerts to chat. Without this platform
layer, each consumer would have to roll its own grouping and dedup
logic.

Per-attachment `maxContentLength` is introduced at the same time because
bulk alert documents (full ES source) can be large. A single global
truncation limit would either under-truncate small attachments or
over-truncate large ones. Delegating the limit to the attachment type
registration lets each type declare its own budget independently.

Closes: elastic/security-team#17544
Epic: elastic/security-team#17311

## Changes

**Types and contracts**
- `AttachmentGroup` type + `isAttachmentGroup` predicate added to
`versioned_attachment.ts`
- `group_id` and `description` optional fields added to `Attachment`,
`AttachmentInput`, and `VersionedAttachment`
- `plugin_contract.ts` exports updated to include `AttachmentGroup`
- `maxContentLength?: number` added to `AttachmentTypeDefinition` —
per-type inline truncation limit (characters), defaults to 10 000 if
absent.


**Client-side logic**
- `flatten_attachments.ts` — new canonical serialization boundary;
stamps `group_id` and `description` on group items
- `remove_attachment_from_list.ts` — handles group-id-based bulk removal
(removes all items sharing a `group_id`)
- `upsert_attachments_into_list.ts` — updated to handle
`AttachmentGroup` alongside `AttachmentInput`
- `build_optimistic_attachments.ts` — preserves `group_id` and
`description` on fallback attachments

**UI**
- `attachment_group_pill.tsx` — new chip component for rendering an
`AttachmentGroup` in the input row (same visual style as
`AttachmentPill`)
- `attachment_pills_row.tsx` / `conversation_input.tsx` — wired to
render `AttachmentGroupPill` for groups
- `round_attachment_references.tsx` — deduplicates attachment refs by
`group_id` (actor-filter check now correctly runs before the
`seenGroupIds` slot is consumed)

**Server pipeline**
- `chat.ts` — accepts and forwards `group_id` / `description` from
request body
- `validate_attachment.ts` — passes `group_id` and `description` through
to state manager
- `attachment_state_manager.ts` — persists `group_id` to
`VersionedAttachment`
- `prepare_conversation.ts` / `attachment_presentation.ts` — threads
`group_id` and per-attachment `maxContentLength` through to agent
execution
- `attachment_presentation.ts` — replaces the flat `maxContentLength`
config option with `resolveMaxContentLength?: (attachment) => number |
undefined`, a per-attachment resolver. `prepare_conversation.ts` wires
this to `attachmentsService.getTypeDefinition(type)?.maxContentLength`
so any attachment type can declare its own inline truncation limit via
its type registration.
- XML attribute `id` renamed to `attachment_id` in inline and summary
attachment nodes, and in the LLM instructions, to remove ambiguity.

**Tests**
- New: `flatten_attachments.test.ts`,
`remove_attachment_from_list.test.ts`, `versioned_attachment.test.ts`,
`round_attachment_references.test.tsx`
- Updated: `upsert_attachments_into_list.test.ts`,
`build_optimistic_attachments.test.ts`,
`attachment_presentation.test.ts`

### Checklist

- [x] Any text added follows [EUI's writing
guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses
sentence case text and includes [i18n
support](https://github.com/elastic/kibana/blob/main/src/platform/packages/shared/kbn-i18n/README.md)
- [ ]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [ ] If a plugin configuration key changed, check if it needs to be
allowlisted in the cloud and added to the [docker
list](https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker)
- [ ] This was checked for breaking HTTP API changes, and any breaking
changes have been approved by the breaking-change committee. The
`release_note:breaking` label should be applied in these situations.
- [ ] [Flaky Test
Runner](https://ci-stats.kibana.dev/trigger_flaky_test_runner/1) was
used on any tests changed
- [x] The PR description includes the appropriate Release Notes section,
and the correct `release_note:*` label is applied per the
[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)
- [x] Review the [backport
guidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)
and apply applicable `backport:*` labels.

### Identify risks

- **Data loss / corruption:** Low. `group_id` and `description` are
optional fields appended to `VersionedAttachment`. Existing saved
conversations have neither field; all read paths guard on `!==
undefined`, so no migration is needed and existing data is unaffected.
- **Regressions:** Low. `AttachmentGroup` has no producers until the
follow-up security PR lands. All existing `AttachmentInput` paths are
unchanged. The `flattenAttachments` function is additive — it handles
both plain `AttachmentInput` and `AttachmentGroup` and existing call
sites have been updated.
- **Performance:** Negligible. The only new overhead is a `Set`-based
group-id dedup during `RoundAttachmentReferences` rendering.
- **Hard-to-test:** The actor-filter / `seenGroupIds` ordering edge case
(filter must run before consuming the Set slot) is subtle but is now
covered by a dedicated test.

### Release note

> No user-facing changes.

**Suggested label:** `release_note:skip`

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

…stem (elastic#270903)

# Summary
This PR is extracted from
[elastic#270286](elastic#270286) as the first of
two stacked PRs. This first PR contains the needed changes in Agent
Builder to support adding several attachments as a single batch to the
chat. This followup [PR](elastic#270904)
adds the possibility bulk add Alerts to the chat.

## What

This PR introduces `AttachmentGroup` as a client-side grouping primitive
and `group_id` as a first-class optional field on `Attachment`,
`VersionedAttachment`, and `AttachmentInput`. The group concept is
dissolved at the `flattenAttachments` serialization boundary —
individual items are stamped with `group_id` — and the full pipeline
(server routes, state manager, agent execution) threads the field
through to persistence and presentation.

## Why

Enables consumers (e.g. the Security Solution bulk-alerts feature) to
attach a batch of items as a single logical group, have them
deduplicated to one chip in chat history, and removed atomically. The
[follow-up PR](elastic#270904) shows the
first concrete use: bulk-adding alerts to chat. Without this platform
layer, each consumer would have to roll its own grouping and dedup
logic.

Per-attachment `maxContentLength` is introduced at the same time because
bulk alert documents (full ES source) can be large. A single global
truncation limit would either under-truncate small attachments or
over-truncate large ones. Delegating the limit to the attachment type
registration lets each type declare its own budget independently.

Closes: elastic/security-team#17544
Epic: elastic/security-team#17311

## Changes

**Types and contracts**
- `AttachmentGroup` type + `isAttachmentGroup` predicate added to
`versioned_attachment.ts`
- `group_id` and `description` optional fields added to `Attachment`,
`AttachmentInput`, and `VersionedAttachment`
- `plugin_contract.ts` exports updated to include `AttachmentGroup`
- `maxContentLength?: number` added to `AttachmentTypeDefinition` —
per-type inline truncation limit (characters), defaults to 10 000 if
absent.


**Client-side logic**
- `flatten_attachments.ts` — new canonical serialization boundary;
stamps `group_id` and `description` on group items
- `remove_attachment_from_list.ts` — handles group-id-based bulk removal
(removes all items sharing a `group_id`)
- `upsert_attachments_into_list.ts` — updated to handle
`AttachmentGroup` alongside `AttachmentInput`
- `build_optimistic_attachments.ts` — preserves `group_id` and
`description` on fallback attachments

**UI**
- `attachment_group_pill.tsx` — new chip component for rendering an
`AttachmentGroup` in the input row (same visual style as
`AttachmentPill`)
- `attachment_pills_row.tsx` / `conversation_input.tsx` — wired to
render `AttachmentGroupPill` for groups
- `round_attachment_references.tsx` — deduplicates attachment refs by
`group_id` (actor-filter check now correctly runs before the
`seenGroupIds` slot is consumed)

**Server pipeline**
- `chat.ts` — accepts and forwards `group_id` / `description` from
request body
- `validate_attachment.ts` — passes `group_id` and `description` through
to state manager
- `attachment_state_manager.ts` — persists `group_id` to
`VersionedAttachment`
- `prepare_conversation.ts` / `attachment_presentation.ts` — threads
`group_id` and per-attachment `maxContentLength` through to agent
execution
- `attachment_presentation.ts` — replaces the flat `maxContentLength`
config option with `resolveMaxContentLength?: (attachment) => number |
undefined`, a per-attachment resolver. `prepare_conversation.ts` wires
this to `attachmentsService.getTypeDefinition(type)?.maxContentLength`
so any attachment type can declare its own inline truncation limit via
its type registration.
- XML attribute `id` renamed to `attachment_id` in inline and summary
attachment nodes, and in the LLM instructions, to remove ambiguity.

**Tests**
- New: `flatten_attachments.test.ts`,
`remove_attachment_from_list.test.ts`, `versioned_attachment.test.ts`,
`round_attachment_references.test.tsx`
- Updated: `upsert_attachments_into_list.test.ts`,
`build_optimistic_attachments.test.ts`,
`attachment_presentation.test.ts`

### Checklist

- [x] Any text added follows [EUI's writing
guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses
sentence case text and includes [i18n
support](https://github.com/elastic/kibana/blob/main/src/platform/packages/shared/kbn-i18n/README.md)
- [ ]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [ ] If a plugin configuration key changed, check if it needs to be
allowlisted in the cloud and added to the [docker
list](https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker)
- [ ] This was checked for breaking HTTP API changes, and any breaking
changes have been approved by the breaking-change committee. The
`release_note:breaking` label should be applied in these situations.
- [ ] [Flaky Test
Runner](https://ci-stats.kibana.dev/trigger_flaky_test_runner/1) was
used on any tests changed
- [x] The PR description includes the appropriate Release Notes section,
and the correct `release_note:*` label is applied per the
[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)
- [x] Review the [backport
guidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)
and apply applicable `backport:*` labels.

### Identify risks

- **Data loss / corruption:** Low. `group_id` and `description` are
optional fields appended to `VersionedAttachment`. Existing saved
conversations have neither field; all read paths guard on `!==
undefined`, so no migration is needed and existing data is unaffected.
- **Regressions:** Low. `AttachmentGroup` has no producers until the
follow-up security PR lands. All existing `AttachmentInput` paths are
unchanged. The `flattenAttachments` function is additive — it handles
both plain `AttachmentInput` and `AttachmentGroup` and existing call
sites have been updated.
- **Performance:** Negligible. The only new overhead is a `Set`-based
group-id dedup during `RoundAttachmentReferences` rendering.
- **Hard-to-test:** The actor-filter / `seenGroupIds` ordering edge case
(filter must run before consuming the Set slot) is subtle but is now
covered by a dedicated test.

### Release note

> No user-facing changes.

**Suggested label:** `release_note:skip`

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>